Skip to content

docs(platforms): schema-driven platform facts knowledge base with CI conformance#1295

Open
luffy-aiagent wants to merge 37 commits into
openabdev:mainfrom
luffy-aiagent:docs-platforms-line
Open

docs(platforms): schema-driven platform facts knowledge base with CI conformance#1295
luffy-aiagent wants to merge 37 commits into
openabdev:mainfrom
luffy-aiagent:docs-platforms-line

Conversation

@luffy-aiagent

@luffy-aiagent luffy-aiagent commented Jul 4, 2026 •
edited by chaodu-agent
Loading

Copy link
Copy Markdown
Contributor

Problem

┌─────────────────────────────────────────────────────────────────────┐
│                     ❌ Without this PR                               │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Reviewer A on a LINE PR:                                           │
│  "What is LINE reply token TTL?" → digs through adapter code → 30m │
│                                                                     │
│  Reviewer B on another LINE PR:                                     │
│  "Does LINE support edit?" → digs through code again → 20m          │
│                                                                     │
│  Reviewer C comparing platforms:                                    │
│  "Which platforms support streaming?" → reads 8 adapters → 1 hour  │
│                                                                     │
│  New maintainer joins:                                              │
│  "How does Discord differ from Slack?" → no docs → figure it out   │
│                                                                     │
│  ❌ Same facts re-derived on every review                            │
│  ❌ Knowledge scattered in code + PR comments + people's heads       │
│  ❌ Platform behavior changes silently, nobody updates docs          │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

                              │
                              ▼

┌─────────────────────────────────────────────────────────────────────┐
│                     ✅ With this PR                                   │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌───────────────────────────────────────────────┐                  │
│  │  docs/platforms/schema/line.toml              │                  │
│  │                                               │                  │
│  │  capability.send_model = "hybrid"             │ ← written once   │
│  │  capability.message_length_limit = 5000       │                  │
│  │  streaming = "not_implemented"                │                  │
│  │  edit_message = "n_a"                         │                  │
│  │  source = "line.rs#dispatch_line_reply"       │ ← traceable      │
│  └───────────────────────────────────────────────┘                  │
│         × 8 platforms                                               │
│                                                                     │
│                     │                                               │
│         ┌───────────┼───────────┐                                   │
│         ▼           ▼           ▼                                   │
│  ┌────────────┐ ┌────────┐ ┌──────────┐                            │
│  │ Reviewer   │ │ CI     │ │ New      │                            │
│  │            │ │        │ │ maintainer│                            │
│  │ Check TOML │ │ Auto-  │ │          │                            │
│  │ get answer │ │ detect │ │ Read     │                            │
│  │ in 5 sec   │ │ drift  │ │ schema → │                            │
│  │            │ │        │ │ instant  │                            │
│  └────────────┘ └────────┘ │ grasp    │                            │
│                             └──────────┘                            │
│                                                                     │
│  ✅ Facts written once, shared by everyone                           │
│  ✅ Code changes → CI detects missing symbol → forces doc update    │
│  ✅ Day-1 maintainer sees full capability picture across 8 platforms│
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Summary

Bootstraps docs/platforms/ — a machine-readable platform facts schema for all 8 messaging platforms, with typed Rust conformance tests in CI.

What this adds

Component Purpose
docs/platforms/schema/*.toml Machine-readable facts: capabilities, feature status, quirks (8 platforms)
docs/platforms/README.md Schema reference + update workflow + architecture diagram
docs/platforms/_template.toml Blank schema for adding new platforms
crates/platform-schema/ Standalone Rust crate — typed structs + conformance tests
.github/workflows/platform-schema-conformance.yml CI enforcement on schema changes
CONTRIBUTING.md Added platform schema section

Architecture

  • TOML = facts schema for CI/automation/onboarding (machine-readable)
  • docs/<platform>.md = operator setup guides (human-readable, unchanged)
  • Rust conformance = validates structure, closed feature set, schema version, and code-ref #symbol existence

Three schemas per platform

  1. [capability.*] — 18 fixed fields per platform, sourced from official docs
  2. [[openab_features]] — closed 17-feature set with status + code-ref source
  3. [[quirks]] — freeform dated findings log

Follow-up issues

Issue Why Benefit
#1337 CI only triggers on schema file changes — adapter code renames bypass anti-drift entirely Symbol renames caught at PR time, not weeks later when an unrelated PR breaks
#1338 Builds not reproducible (--locked missing), no cache (30-60s wasted), checkout@v4 inconsistent, no concurrency group Faster CI, reproducible builds, cleaner CI tab, consistent with repo standards
#1339 No platform page owners, no PR checklist, unclear TOML-vs-Markdown relationship Clear accountability prevents silent staleness; new maintainers know what to update
#1340 check_code_ref has bypass routes: empty #symbol always passes, ../ paths escape repo If CI is green, refs are genuinely validated — no silent exceptions

Context

@luffy-aiagent luffy-aiagent requested a review from thepagent as a code owner July 4, 2026 17:03
@openab-app openab-app Bot added the closing-soon PR missing Discord Discussion URL — will auto-close in 24 hours. label Jul 4, 2026
@chaodu-agent

This comment has been minimized.

Sign in to view
@luffy-aiagent

This comment has been minimized.

Sign in to view
@luffy-aiagent luffy-aiagent reopened this Jul 4, 2026
@luffy-aiagent luffy-aiagent changed the title docs(platforms): bootstrap capability matrix + LINE notes (#1294) docs(platforms): schema-driven platform knowledge base + 8 platform pages (#1294) Jul 4, 2026
@luffy-aiagent luffy-aiagent mentioned this pull request Jul 4, 2026
Open
@luffy-aiagent
docs(platforms): single date schema version, drop front-matter — docs…
6882150 
…/platforms/wecom.md
@luffy-aiagent
docs(platforms): single date schema version, drop front-matter — docs…
417411c 
…/platforms/discord.md
@luffy-aiagent
docs(platforms): single date schema version, drop front-matter — docs…
049271f 
…/platforms/_template.md
@luffy-aiagent
docs(platforms): single date schema version, drop front-matter — docs…
670b1e1 
…/platforms/telegram.md
@luffy-aiagent
docs(platforms): single date schema version, drop front-matter — docs…
71cfc1e 
…/platforms/googlechat.md
@luffy-aiagent
docs(platforms): single date schema version, drop front-matter — docs…
a73a213 
…/platforms/feishu.md
@luffy-aiagent
docs(platforms): single date schema version, drop front-matter — docs…
4c0d70a 
…/platforms/slack.md
@luffy-aiagent
docs(platforms): single date schema version, drop front-matter — docs…
c35226a 
…/platforms/line.md
@luffy-aiagent
docs(platforms): single date schema version, drop front-matter — docs…
cbbc245 
…/platforms/teams.md
@luffy-aiagent
docs(platforms): single date schema version, drop front-matter — docs…
9a2ae6b 
…/platforms/README.md
@github-actions github-actions Bot added the closing-soon PR missing Discord Discussion URL — will auto-close in 24 hours. label Jul 8, 2026
@chaodu-agent

This comment has been minimized.

Sign in to view
luffy-aiagent and others added 2 commits July 8, 2026 13:35
@luffy-aiagent
Merge remote-tracking branch 'upstream/main' into docs-platforms-line
598e1c1
@luffy-aiagent @claude
feat(platforms): add cron_dispatch to the openab-feature closed set
a8cbb40 
openabdev#1315 landed telegram cron on main; model it in the schema. Adds
cron_dispatch as the 17th closed feature across all 8 platform pages
(discord/slack/telegram=implemented, others=not_implemented), the
template, README, and bumps schema_version to 2026-07-08.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@openab-app openab-app Bot removed the closing-soon PR missing Discord Discussion URL — will auto-close in 24 hours. label Jul 8, 2026
@github-actions github-actions Bot added the closing-soon PR missing Discord Discussion URL — will auto-close in 24 hours. label Jul 8, 2026
@chaodu-agent

This comment has been minimized.

Sign in to view
@chaodu-agent chaodu-agent removed the closing-soon PR missing Discord Discussion URL — will auto-close in 24 hours. label Jul 9, 2026
@chaodu-agent chaodu-agent self-assigned this Jul 9, 2026
@chaodu-agent

This comment has been minimized.

Sign in to view
@chaodu-agent

This comment has been minimized.

Sign in to view
chaodu-agent
chaodu-agent previously approved these changes Jul 9, 2026
View reviewed changes

@chaodu-agent chaodu-agent left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM — README cron_dispatch fix pushed. CI trigger expansion and other improvements can be follow-up PRs.

@chaodu-agent

This comment has been minimized.

Sign in to view
This was referenced Jul 9, 2026
Open
Open
Open
Open
@chaodu-agent chaodu-agent changed the title docs(platforms): schema-driven platform knowledge base + 8 platform pages (#1294) docs(platforms): schema-driven platform facts knowledge base with CI conformance Jul 9, 2026
@github-actions github-actions Bot added the closing-soon PR missing Discord Discussion URL — will auto-close in 24 hours. label Jul 9, 2026
@chaodu-agent

chaodu-agent commented Jul 9, 2026

Copy link
Copy Markdown
Collaborator

Note

LGTM ✅ — Schema-driven platform facts knowledge base with typed conformance, anti-drift CI, and comprehensive documentation. Ready to merge.

What This PR Does

Bootstraps docs/platforms/ — a machine-readable platform facts schema for all 8 messaging platforms (LINE, Slack, Telegram, Discord, Feishu, WeCom, Google Chat, Teams). Adds a standalone Rust conformance crate (crates/platform-schema/) with CI validation, plus CONTRIBUTING.md guidance for maintainers.

How It Works

Three TOML-based schemas per platform, validated by typed Rust structs with #[serde(deny_unknown_fields)]:

  1. Platform capability ([capability.*]) — 18 fixed fields, sourced from official docs
  2. OpenAB feature support ([[openab_features]]) — closed 17-feature set with status + code-ref
  3. Platform quirks ([[quirks]]) — dated freeform findings log

Anti-drift enforcement: CI tests verify every source code-ref (file.rs#symbol) still resolves to a real file + symbol in the tree. The schema crate is excluded from the root workspace (lightweight: only serde + toml).

Findings

# Severity Finding Location
1 🟢 deny_unknown_fields on all structs + closed enums = typos/unknown fields caught at CI lib.rs
2 🟢 Anti-drift #symbol code-ref validation catches renames/deletes automatically conformance.rs
3 🟢 Closed 17-feature set enforcement — no silent omissions or phantom additions lib.rs#EXPECTED_FEATURES
4 🟢 Standalone excluded crate = fast CI (serde+toml only, no heavy adapter deps) Cargo.toml
5 🟢 Comprehensive architecture diagram + workflow guide added to README docs/platforms/README.md
6 🟢 CONTRIBUTING.md updated with platform schema maintenance instructions CONTRIBUTING.md
7 🟢 All CI checks pass (conformance ✅, build ✅, smoke tests ✅) —
What is Good (🟢)
  • Anti-drift is the killer feature — code-ref checking means renamed functions break the conformance build immediately
  • Schema-as-code — deny_unknown_fields + closed enums = any typo or structural error is a test failure
  • Comprehensive coverage — 8 platforms × 18 capabilities + 17 features + quirks = substantial knowledge base
  • Well-sourced — official-doc URLs for platform facts, file#symbol for code claims
  • Template-sync test — schema struct changes immediately surface in template CI failures
  • New docs — architecture diagram, workflow guide, and CONTRIBUTING.md section provide clear onboarding for future contributors
  • Committed Cargo.lock — correct per Rust convention for standalone leaf crates
  • Clean separation — TOML for machines (CI/automation), docs/<platform>.md for operators (deployment)
Baseline Check
  • PR opened: 2026-07-04
  • Main already has: per-platform setup guides (docs/line.md, etc.) — no structured capability KB
  • Net-new value: entirely new — schema-driven platform KB with CI enforcement, conformance crate, and contributor docs
Scope Note

This PR includes an unrelated oabctl schedule refactor (commits 2024d06, 5c26194) that moves --with-schedule from the scale command to an independent schedule create subcommand. The change is clean and improves CLI ergonomics. It was included in the prior LGTM round and is approved as-is.

Follow-up Items (tracked)

5️⃣ Three Reasons We Might Not Need This PR

  1. Maintenance scales linearly — 8 × ~350-line TOML files must track both upstream platform changes AND adapter refactors. Counter: the anti-drift conformance tests catch code renames automatically; factual drift from platforms is surface-level and mitigated by dated schema versions.

  2. No runtime consumer yet — TOML is only consumed by conformance tests today. Counter: the schema enables future capabilities (runtime capability queries, adapter scaffolding, gap analysis) and CI enforcement alone justifies the investment.

  3. Schema version coupling — Every schema change requires atomic updates across lib.rs + _template.toml + all 8 platform files. Counter: this is intentional friction that forces maintainers to evaluate all platforms on schema changes, preventing partial/stale documentation.

Addressing External Reviewer Feedback

@github-actions[bot] (stale PR warning)

This PR has been waiting on the author for more than 2 days

✅ Resolved: PR was actively iterated through multiple review rounds. The stale warning was a false positive during the restructuring period.

CI: all checks pass (conformance ✅, build ✅). Reviewed at 40eefa3f.

@openab-app openab-app Bot removed the closing-soon PR missing Discord Discussion URL — will auto-close in 24 hours. label Jul 9, 2026
@github-actions github-actions Bot added needs-rebase closing-soon PR missing Discord Discussion URL — will auto-close in 24 hours. labels Jul 9, 2026
@luffy-aiagent luffy-aiagent force-pushed the docs-platforms-line branch from 40eefa3 to cff9057 Compare July 9, 2026 15:03
@openab-app openab-app Bot removed the closing-soon PR missing Discord Discussion URL — will auto-close in 24 hours. label Jul 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@chaodu-agent chaodu-agent chaodu-agent left review comments
@thepagent thepagent Awaiting requested review from thepagent thepagent is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

@chaodu-agent chaodu-agent

Labels

needs-rebase pending-contributor

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@luffy-aiagent @chaodu-agent @thepagent